Release 10.1A: OpenEdge Development:
Progress Dynamics Basic Development

Error message checking include file (checkerr.i)

The include file aferrortxt.i takes care of formatting messages into a standard format in preparation for returning them to the client to be presented to the user. As the examples above show, simply returning the message text string from any of the standard validation procedures results in the errors being processed correctly. The wrapper code that runs the validation procedures handles the messages for you.

In other cases, however, you might need to process errors yourself (for example, from stand-alone business logic procedures that you write, as described later). There is another standard include file, called checkerr.i, that you should always use when checking for errors within your own logic procedure, instead of doing an IF ERROR-STATUS:ERROR check manually.

The include file handles the checking of the error status. If an error occurred, it handles displaying of the error message or passing on of the error message and return value back to the caller. It also contains code to build a return value from the Progress Dynamics get-message method if the RETURN-VALUE is empty. This is a very flexible include file and should cater for all scenarios. Table 10–2 lists the named arguments.

Table 10–2: Named arguments for checkerr.i

Argument	Description
&display-error = YES	Displays the error if not in a transaction. This invokes the standard Progress Dynamics message dialog box, and should, therefore, be done only if you are in client-side code that can present the message dialog box to the user.
&return-only = YES	Does not pass on the error but does a RETURN.
&return-error = YES	Passes on the error. The code defaults to this if there is currently an open transaction.
&no-return = YES	Does not return when finished; instead, this form lets you decide what to do in the code following the include file reference.
&ignore-errorlist = YES	Does not use get-message errors at all (use with caution). get-message is a standard Progress Dynamics method that retrieves error messages generated by Progress, in addition to any messages generated by the application.
&define-only = YES	Defines the variables you need but takes no other action. The checkerr.i include file defines several local variables that are needed in its processing, including cMessageList, cMessageButton, and cMessageAnswer, which are described below.

The &define-only argument is therefore useful if checkerr.i is included more than once in the same file but separate procedures. If you place this code at the top of your file, the necessary variables will be defined once, and no other action will take place, as shown:

{checkerr.i &define-only = YES}

When you are using checkerr.i in server-side business logic, normally some combination of the arguments in Table 10–2 that handle the RETURN statement are the ones you will use in your code. If you are displaying an error message in client code from checkerr.i, then arguments listed in Table 10–3 are also additionally available.

Table 10–3: Additional arguments for checkerr.i 

Argument	Description
&message-type	Type of message, one of 'MES' (ordinary message) 'INF' (informational message) 'WAR' (warning) 'ERR' (error) 'HAL' (halt) 'QUE' (question) The default is 'ERR'.
&message-buttons	Comma list of buttons to be placed into the message dialog box the default is OK.
&button-default	Default button, the default is OK.
&button-cancel	Cancel button, the default is 'OK' except for QUEstion messages.
&message-title	Title for the message dialog box; the default is the empty string.
&display-empty	YES—Displays message dialog box even if empty, the default = YES.

Table 10–4 lists the arguments available if the message type is QUE for Question.

Table 10–4: Question arguments 

Argument	Description
&message-data type	Data type, the default is Character.
&message-format	Format of question, the default is 'CHR(35).
&default-answer	Default answer, the default is empty.

Note: For a question message type, the defaults change to &message-buttons = 'OK,CANCEL', &button-default = 'OK', &button-cancel = 'CANCEL'.

The following rules apply when you use the checkerr.i include file:

Required logical arguments must be passed unquoted as YES or NO. Other text arguments must be single quoted literals (for example, 'text' or unquoted variables), and if the literals require spaces, they should be double-quoted then single-quoted (for example, "'text'").
All arguments can be left blank, in which case the error will not be displayed and will be passed on with a return error.
If everything is left blank except display-error is YES, then the error will be displayed using the Progress Dynamics message dialog box and a standard return statement done.
If in a transaction, the error will be passed on regardless, unless {&no-return} is set to YES.
If display error is set to YES, the default is to do a return only rather than return error.
If display error is set to NO, the default is to do a return error to pass the error on.
If return-only is set to YES, this will override any other return settings and let you regain control.

Following the include file, if {&no-return} is set to YES. Table 10–5 lists the variable values available.

Table 10–5: NO-RETURN variables 

Variable	Value
cMessageList	CHR(3)-delimited list of error messages.
cMessageButton	Button pressed.
cMessageAnswer	Answer if question dialog box is used.

Here are a few examples of using the checkerr.i include file. First, another standard Progress Dynamics include reference is required in every procedure that uses other Progress Dynamics includes, such as checkerr.i. This is afglobals.i, which defines global references to some of the Progress Dynamics managers.

This example runs a business logic procedure using the launch.i mechanism (described in more detail in Chapter 11 "Building Advanced Business Logic in a Progress Dynamics Application"). It then uses checkerr.i upon return to intercept any errors that occur. For the sake of simplicity, the first example simply displays the error, using the standard Progress Dynamics message dialog box, so that you can see how that works, even though you would, of course, not invoke this display directly from a server-side logic procedure.

Here is the code that launches the procedure and a reference to checkerr.i to display an error, if there is one. Pass in the name of the external procedure to run persistent on the server, the name of the internal procedure to run in its handle, whether to invoke it on the AppServer, and a list of parameters to it. The internal procedure validateDatasetQuery uses aferrortxt.i to return error number AF:114 if there is an error in the names of the input parameters. It is this error that you intercept here, as shown:

{afglobals.i} {launch.i &PLIP = 'af/app/gscddxmlp.p' &IProc = 'validateDatasetQuery' &OnApp = 'NO' &PList = "('rycso','rycsf','smartobject_obj,smartobject_obj','',no)" &AutoKill = YES} {checkerr.i &display-error = YES} }.

If you modify the parameter list to the validateDatasetQuery procedure so that it is no longer valid, an error message is generated and picked up by checkerr.i:

{afglobals.i} {launch.i &PLIP = 'af/app/gscddxmlp.p' &IProc = 'validateDatasetQuery' &OnApp = 'NO' &PList = "('rycso','rycsf','smartobject_obj,smartxxxxx_obj','',no)" &AutoKill = YES} {checkerr.i &display-error = YES}.